Loan Origination APIs

These endpoints cover application intake, automated assessment, and bank decisioning for SME merchant loans.

Authentication

All requests require:

Authorization: Bearer <your-api-token>

1. Create Loan Application

Endpoint

POST /api/v1/loan-applications

Description

Create a new loan application for a merchant from the Credify merchant dataset.

Sample request

{
  "merchant_id": "MCH-12345",
  "business_name": "Tech Store LLC",
  "requested_amount": 50000.0,
  "loan_purpose": "inventory",
  "monthly_sales_volume": 125000.0,
  "platform_type": "shopify",
  "requested_term_months": 12
}

Sample response

{
  "application_id": "APP-2026-003",
  "merchant_id": "MCH-12345",
  "business_name": "Tech Store LLC",
  "requested_amount": 50000.0,
  "loan_purpose": "inventory",
  "monthly_sales_volume": 125000.0,
  "platform_type": "shopify",
  "requested_term_months": 12,
  "currency": "EGP",
  "status": "submitted",
  "created_at": "2026-04-23"
}

Field	Type	Required	Description
merchant_id	string	Yes	Unique merchant identifier from the Credify merchant dataset
business_name	string	Yes	Merchant legal business name
requested_amount	decimal	Yes	Requested loan amount in EGP
loan_purpose	enum	Yes	inventory, working_capital, expansion, equipment
monthly_sales_volume	decimal	Yes	Average monthly GMV from POS or commerce channels
platform_type	enum	Yes	shopify, woocommerce, amazon_seller
requested_term_months	integer	Yes	Requested duration in months

2. Credit Assessment

Endpoint

GET /api/v1/loan-applications/{application_id}/assessment

Description

Retrieve the credit assessment for a submitted loan application. Scores the application based on sales performance and business age, and returns a risk rating with recommended lending terms.

Sample response

{
  "application_id": "APP-2026-001",
  "sales_performance_score": 82.5,
  "business_age_months": 30,
  "default_risk_rating": "low",
  "recommended_amount": 46000.0,
  "recommended_interest_rate": 16.5,
  "assessment_notes": "Strong sales coverage relative to request. Recommend standard approval path."
}

Field	Type	Direction	Description
application_id	string	Path	Loan application reference
sales_performance_score	decimal	Response	Performance score from 0 to 100
business_age_months	integer	Response	Merchant operating age in months
default_risk_rating	enum	Response	low, medium, high
recommended_amount	decimal	Response	Suggested lendable amount
recommended_interest_rate	decimal	Response	Suggested APR
assessment_notes	string	Response	Summary lending note for review

3. Loan Approval Decision

Endpoint

POST /api/v1/loan-applications/{application_id}/decisions

Description

Record the final bank decision on a submitted application. Approved decisions automatically create a new active loan account.

Sample request

{
  "application_id": "APP-2026-001",
  "decision": "approved",
  "approved_amount": 45000.0,
  "interest_rate": 16.5,
  "term_months": 12,
  "decision_maker_id": "BANK-OFFICER-19"
}

Sample response

{
  "application_id": "APP-2026-001",
  "decision": "approved",
  "approved_amount": 45000.0,
  "interest_rate": 16.5,
  "term_months": 12,
  "rejection_reason": null,
  "decision_maker_id": "BANK-OFFICER-19",
  "loan_id": "LN-2026-002",
  "status": "approved"
}

Field	Type	Required	Description
decision	enum	Yes	approved, rejected, pending_review
approved_amount	decimal	If approved	Final approved amount
interest_rate	decimal	If approved	Final APR
term_months	integer	If approved	Final loan term
rejection_reason	string	If rejected	Rejection note
decision_maker_id	string	Yes	Bank officer or system identifier